Skip to content

docs(mister): name the device-under-test repository, now that it exists - #434

Merged
doublegate merged 1 commit into
mainfrom
docs/mister-sibling-repo-url
Aug 21, 2026
Merged

docs(mister): name the device-under-test repository, now that it exists#434
doublegate merged 1 commit into
mainfrom
docs/mister-sibling-repo-url

Conversation

@doublegate

Copy link
Copy Markdown
Owner

docs/mister.md described a "sibling repository (RustyNES_MiSTer)" with no link, because there was nothing to link to. There is now: https://github.com/doublegate/RustyNES_MiSTer (private).

Two additions beyond the URL

The cross-repository coupling is named, because breaking it is silent

tb/checkpoint.h over there reimplements Observable::encode from here, and tb/checkpoint_selftest.cpp asserts it against the same hardcoded vector the_wire_encoding_is_pinned_to_a_fixed_vector pins on this side.

That pairing is the entire guard against the top-ranked risk at this rung: a packing disagreement between the two halves produces a hash mismatch indistinguishable from a wrong DUT, and would be debugged as one. So the doc now says plainly that changing encode here without changing checkpoint.h there breaks co-simulation in the hardest way to diagnose, and that the selftest is the first thing to run after touching either.

A coupling spanning two repositories has nothing mechanical watching it — which is exactly why it belongs where the person editing the encoding will read it.

Verified rather than asserted before writing it down — both files parsed and their vectors compared byte for byte:

rust: 16 bytes  08 07 06 05 04 03 02 01 f5 c5 23 81 a9 01 05 00
cpp : 16 bytes  08 07 06 05 04 03 02 01 f5 c5 23 81 a9 01 05 00

plus the selftest re-run against merged main, five checks green.

Worth recording how that nearly went wrong: the first comparison was a grep -A4 over the Rust array and returned three bytes — rustfmt had reformatted the literal one element per line, so the context window was too small. Three bytes against sixteen reads as a mismatch. The published comparison parses both literals properly.

ADR 0037's licence hedge is resolved, and inverted

ADR 0037 recorded that a GPL-2.0-only file anywhere in the MiSTer framework's sys/ would force the RTL to GPL-2.0-or-later, and that the tabulation had to happen before any RTL existed. It has — all 57 files read and classified.

There is no GPL-2.0-only file. Four are GPL-3.0-or-later, one being hps_io.sv, which is how a core receives a ROM and reaches the OSD; no core functions without it. GPL-2.0-or-later combines upward into GPL-3 and GPL-3.0-or-later does not reduce, so the combined bitstream must be GPL-3.0-or-later — already this project's licence.

The hedge is inverted by the evidence rather than confirmed by it, and the decision is made at zero lines of RTL rather than ten thousand, which was the point of ordering the audit first.

Docs only — no source, no manifests, no core.

The spec described a "sibling repository (`RustyNES_MiSTer`)" with no link,
because at the time there was nothing to link to. There is now:
https://github.com/doublegate/RustyNES_MiSTer, private.

Two additions beyond the URL, both about things a reader of this document
needs and could not previously get.

THE CROSS-REPOSITORY COUPLING IS NAMED, BECAUSE BREAKING IT IS SILENT

`tb/checkpoint.h` over there reimplements `Observable::encode` from here, and
`tb/checkpoint_selftest.cpp` asserts it against the same hardcoded vector
`the_wire_encoding_is_pinned_to_a_fixed_vector` pins on this side. That pairing
is the entire guard against the top-ranked risk at this rung: a packing
disagreement between the two halves produces a hash mismatch indistinguishable
from a wrong DUT, and it would be debugged as one.

So the document now states plainly that changing `encode` here without
changing `checkpoint.h` there breaks co-simulation in the way that is hardest
to diagnose, and that the selftest is the first thing to run after touching
either. A coupling that spans two repositories has nothing mechanical watching
it, which is exactly why it has to be written where the person editing the
encoding will read it.

Verified rather than asserted before writing it down: both files were parsed
and their pinned vectors compared byte for byte.

  rust: 16 bytes  08 07 06 05 04 03 02 01 f5 c5 23 81 a9 01 05 00
  cpp : 16 bytes  08 07 06 05 04 03 02 01 f5 c5 23 81 a9 01 05 00

and the selftest re-run against merged main, all five checks green.

Worth recording how that nearly went wrong: the first comparison was a `grep
-A4` over the Rust array, which returned three bytes -- rustfmt had reformatted
the literal one element per line, so the context window was too small. Three
bytes against sixteen reads as a mismatch. The published comparison parses both
literals properly instead.

THE LICENCE HEDGE IN ADR 0037 IS RESOLVED, AND INVERTED

ADR 0037 recorded that a GPL-2.0-ONLY file anywhere in the MiSTer framework's
sys/ would force the RTL to GPL-2.0-or-later, and that the tabulation had to
happen before any RTL existed. It has: all 57 files read and classified.

There is no GPL-2.0-only file. Four are GPL-3.0-OR-LATER, and one of them is
hps_io.sv, which is how a core receives a ROM and reaches the OSD -- no core
functions without it. GPL-2.0-or-later combines upward into GPL-3;
GPL-3.0-or-later does not reduce. The combined bitstream must therefore be
GPL-3.0-or-later, which is already this project's licence.

The hedge is inverted by the evidence rather than confirmed by it, and the
decision is made with zero lines of RTL written rather than ten thousand --
which was the entire point of ordering the audit first.

Docs only. No source, no manifests, no core.
Copilot AI lite review requested due to automatic review settings August 21, 2026 00:22
@coderabbitai

coderabbitai Bot commented Aug 21, 2026

Copy link
Copy Markdown

Important

  • 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: f16b1ac5-56e3-4606-a4cc-36fcfac11521


Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

@github-actions

Copy link
Copy Markdown

Antigravity review (Gemini via Ultra)

Updates documentation to include the repository link, integration points, and license audit details for the device-under-test.

Blocking issues

None found.

Suggestions

  • docs/mister.md:6 and docs/mister.md:21: Linking to a private repository (https://github.com/doublegate/RustyNES_MiSTer) can be frustrating for external readers. Consider adding a brief note explaining who has access, why it is private, or how to request access if applicable.
  • docs/mister.md:23: The phrase "which is the ladder's design rather than a gap" and the reference to "rung 0" rely heavily on context. Ensure this ladder/rung analogy is clearly defined earlier in the document or rephrase for clarity.

Nitpicks

  • docs/mister.md:23: The sentence starting with "The sibling repository holds..." is somewhat run-on. Splitting it into two sentences would improve readability.
  • docs/mister.md:38: "licence" uses the British spelling. Verify this matches the spelling convention (e.g., US English "license") used throughout the rest of the project.

Automated first-pass review by agy on a self-hosted runner -- not a human review.

@doublegate
doublegate merged commit fbf5364 into main Aug 21, 2026
18 of 19 checks passed
@doublegate
doublegate deleted the docs/mister-sibling-repo-url branch August 21, 2026 00:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants